/**
 * Collaborative Story Development Web Application (CSDApp) Copyright Anton
 * Strack 2014
 *
 * This file is part of Collaborative Story Development Application (CSDApp).
 *
 * CSDApp is free software: you can redistribute it and/or modify it under the
 * terms of the GNU General Public License as published by the Free Software
 * Foundation, either version 3 of the License, or any later version.
 *
 * CSDApp is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along with
 * CSDApp. If not, see <http://www.gnu.org/licenses/>.
 *
 */
package csdwa;

import java.util.List;

/**
 * This class provides database access to the specific resource model. It
 * provides CRUD database functionality and it stores it's results as a list.
 * Additionally, through it's methods, it provides access to determine the table
 * name, and query markers that are set for the particular DAO and thus allows
 * other code a means of interacting with this DAO to execute more advanced
 * queries.
 *
 * @author Anton Strack
 */
public interface CsdwaDao<E> {

    /**
     * Select all the beans from the bean table
     *
     * @return the row count indicating if 0 or more beans were retrieved from
     * the database.
     */
    public int selectBeans();

    /**
     * Select a single bean by it's id.
     *
     * @param id the id number of the bean to select.
     * @return 1 or 0, indicating a bean was retrieved or not.
     */
    public int selectBeanById(int id);

    /**
     * Clear the bean list so it doesn't contain any beans.
     */
    public void clearDaoBeans();

    /**
     * Get the bean stored in the dao by it's primary id.
     *
     * @param id the id of the bean to select.
     * @return the bean if it exists in the dao or null if it doesn't
     */
    public E getBeanById(int id);

    /**
     * Save a bean to the database
     *
     * @param bean the bean to insert. The bean id is not required and won't be
     * used. All other bean values are required.
     * @return the auto-generated id key for the new bean row or 0 on failure.
     */
    public int insertBean(E bean);

    /**
     * Update a bean in the database as well as the bean in the dao's beans map.
     *
     * @param bean the bean to update.
     * @return 1 or 0 indicating if the bean was updated or not.
     */
    public int updateBean(E bean);

    /**
     * Deletes the bean from the database
     *
     * @param bean the bean to delete
     * @return 1 or 0 indicating if the bean was deleted or not.
     */
    public int deleteBean(E bean);

    /**
     * Get a list of beans
     *
     * @return a list of bean objects
     */
    public List<E> getBeans();

    /**
     * Get a single bean.
     *
     * @return a single bean in the bean dao.
     */
    public E getBean();

    /**
     * Add a bean in the dao's bean list.
     *
     * @param bean the bean to add or update
     */
    public void addBeanToDao(E bean);

    /**
     * Add a derived value to a select query. This method is used to build the
     * derived query markers.
     *
     * @param derivedColumn the column name that is to be selected. This is the
     * minimum requirement to use the derived value.
     * @param derivedTable the table the derived column is from if not the core
     * table
     * @param derivedCondition the condition needed to select the proper derived
     * from another table * value.
     */
    public void addDerivedValue(String derivedColumn, String derivedTable, String derivedCondition);

    /**
     * This method provides a means to indicate to the dao if it should query
     * the related tables in order to get the values matching the foriegn keys.
     * It is up to the child dao to select and add the related query markers if
     * this is set to true.
     *
     * @param use true to add the related query markers and false to not add
     * them.
     */
    public void setUseRelatedMarkers(boolean use);

    /**
     * Add a query marker to the list of query markers that should be used in
     * the query.
     *
     * @param queryMarker the query marker to add.
     */
    public void addUsingQueryMarker(QueryMarker queryMarker);

    /**
     * Get the query marker value according to the provided query marker.
     *
     * @param queryMarker the query marker to get the value of
     * @return a string representing the dao value of the query marker.
     */
    public String getQueryMarkerValue(QueryMarker queryMarker);

    /**
     * Set the value of the query marker for the specific dao object.
     *
     * @param queryMarker the query marker to add or update
     * @param value the value of the query marker.
     */
    public void setQueryMarkerValue(QueryMarker queryMarker, String value);

    /**
     * Select the next selection of rows that aren't = to id and have a greater
     * updated date
     *
     * @param id the id to select the next rows after
     * @param limit the number of rows to select
     * @return the number of rows selected.
     */
    public int selectNext(int id, int limit);

    /**
     * Select the previous selection of rows that aren't = to id and have a
     * lesser updated date
     *
     * @param id the id to select the previous rows before
     * @param limit the number of rows to select
     * @return the number of rows selected.
     */
    public int selectPrevious(int id, int limit);

    /**
     * Select a single bean by checking if the search query matches in the name
     * or description field. The search is case insensitive.
     *
     * @param query a string query to search for.
     * @return the number of beans retrieved from the database
     */
    public int selectBeanSearchQuery(String query);
}
